﻿using System;
using System.Xml;
using Notoric.Model.Packaging;

namespace Notoric.Model.Elements
{
    /// <summary>
    /// An abstract base class for custom part descriptor data elements.
    /// </summary>
    /// <remarks>
    /// <para>
    /// A custom part descriptor data element allows anyone to extend a part descriptor
    /// by its own data fields that are not interpreted by the part descriptor, but can
    /// easily be retrieved from it.
    /// </para>
    /// <para>
    /// This may be handy for music section interiors and for exporters to store a composition-level
    /// part data they need. For example, the Common Western Notation section interior (<see cref="CWNotation.MusicSectionInterior"/>)
    /// uses this element to store the number of staves of each part and its usual position in an orchestral score.
    /// A MIDI and MusicXml exporter uses another element that stores the MIDI instrument that plays the part.
    /// </para>
    /// </remarks>
    public abstract class CustomPartDataElement : ModelElement
    {
        #region Constructors

        /// <summary>
        /// Creates a new <see cref="CustomPartDataElement"/> instance.
        /// </summary>
        /// <param name="packagePart">
        /// <para>
        /// Type: <see cref="CompositionPart"/>
        /// </para>
        /// <para>
        /// The package part that owns this element.
        /// </para>
        /// </param>
        /// <param name="owner">
        /// <para>
        /// Type: <see cref="PartDescriptorElement"/>
        /// </para>
        /// <para>
        /// The part descriptor that directly owns this element.
        /// </para>
        /// </param>
        /// <exception cref="ArgumentNullException">
        /// Any of the arguments is <see langword="null"/>.
        /// </exception>
        protected CustomPartDataElement(CompositionPart packagePart, PartDescriptorElement owner)
            : base(packagePart, owner)
        {
        }

        /// <summary>
        /// Creates a new <see cref="CustomPartDataElement"/> instance.
        /// </summary>
        /// <param name="packagePart">
        /// <para>
        /// Type: <see cref="CompositionPart"/>
        /// </para>
        /// <para>
        /// The package part that owns this element.
        /// </para>
        /// </param>
        /// <param name="owner">
        /// <para>
        /// Type: <see cref="PartDescriptorElement"/>
        /// </para>
        /// <para>
        /// The part descriptor that directly owns this element.
        /// </para>
        /// </param>
        /// <param name="element">
        /// <para>
        /// Type: <see cref="XmlElement"/>
        /// </para>
        /// <para>
        /// The XML element that holds the data of this object.
        /// </para>
        /// </param>
        /// <exception cref="ArgumentNullException">
        /// Any of the arguments is <see langword="null"/>.
        /// </exception>
        protected CustomPartDataElement(CompositionPart packagePart, PartDescriptorElement owner, XmlElement element)
            : base(packagePart, owner, element)
        {
        }

        #endregion
    }
}
